Programming With QuickTime VR 2.1
The QuickTime VR Manager provides a number of routines that you can use to handle user actions such as moving the mouse or clicking the mouse button. Normally, QuickTime VR handles all user interaction internally if your application calls the MCIsPlayerEvent function in its main event loop. For code that does not have a main event loop (such as an OpenDoc part), you might need to override QuickTime VR's mouse event handling.
Most applications do not need to use the functions described in this section.
You can use the QTVRGetMouseOverTracking function to get the current state of mouse-over tracking.
Boolean QTVRGetMouseOverTracking (QTVRInstance qtvr);
The QTVRGetMouseOverTracking function returns, as its function result, a Boolean value that indicates whether QuickTime VR is currently handling mouse-over tracking for the QuickTime VR movie specified by the qtvr parameter ( true ) or not ( false ). By default, QuickTime VR tracks mouse movements in a QuickTime VR movie and changes the shape of the cursor as appropriate.
You can use the QTVRSetMouseOverTracking function to set the state of mouse-over tracking.
OSErr QTVRSetMouseOverTracking (QTVRInstance qtvr, Booleanenable);
The QTVRSetMouseOverTracking function sets the mouse-over tracking state of the QuickTime VR movie specified by the qtvr parameter to the state specified by the enable parameter. By default, QuickTime VR tracks mouse movements in a QuickTime VR movie and changes the shape of the cursor as appropriate. If you disable mouse-over tracking (by passing false in the enable parameter), you must call the QTVRMouseEnter , QTVRMouseWithin , and QTVRMouseLeave functions at the appropriate times to handle user actions.
Use QTVRGetMouseOverTracking (described in the section "QTVRGetMouseOverTracking" ) to get the current mouse-over tracking state of a QuickTime VR movie.
You can use the QTVRMouseEnter function to handle the user's moving the cursor into a QuickTime VR movie for which mouse-over tracking is disabled.
OSErr QTVRMouseEnter (
QTVRInstance qtvr,
Pointpt,
UInt32*hotSpotID,
WindowPtr w);
The QTVRMouseEnter function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseEnter also performs any other tasks that are typically performed when the user first moves the cursor into a QuickTime VR movie.
You need to call QTVRMouseEnter only if you have disabled mouse-over tracking for the specified QuickTime VR movie.
Use QTVRSetMouseOverTracking (described in the section "QTVRSetMouseOverTracking" ) to change the mouse-over tracking state of a QuickTime VR movie. Use QTVRMouseWithin (described in the section "QTVRMouseWithin" ) and QTVRMouseLeave (described in the section "QTVRMouseLeave" ) to handle the cursor's remaining in and leaving a QuickTime VR movie.
You can use the QTVRMouseWithin function to handle the user's leaving the cursor in a QuickTime VR movie for which mouse-over tracking is disabled.
OSErr QTVRMouseWithin (QTVRInstance qtvr, Pointpt, UInt32*hotSpotID, WindowPtr w);
The QTVRMouseWithin function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseWithin also performs any other tasks that are typically performed when the user leaves the cursor in a QuickTime VR movie.
You should call QTVRMouseWithin repeatedly for as long as the cursor remains in the specified QuickTime VR movie.
You need to call QTVRMouseWithin only if you have disabled mouse-over tracking for the specified QuickTime VR movie.
Use QTVRSetMouseOverTracking (described in the section "QTVRSetMouseOverTracking" ) to change the mouse-over tracking state of a QuickTime VR movie. Use QTVRMouseEnter (described in the section "QTVRMouseEnter" ) and QTVRMouseLeave (described in the section "QTVRMouseLeave" ) to handle the cursor's entering and leaving a QuickTime VR movie.
You can use the QTVRMouseLeave function to handle the user's moving the cursor out of a QuickTime VR movie for which mouse-over tracking is disabled.
OSErr QTVRMouseLeave (QTVRInstance qtvr, Pointpt, WindowPtr w);
The QTVRMouseLeave function performs any tasks that are typically performed when the user moves the cursor out of a QuickTime VR movie.
You need to call QTVRMouseLeave only if you have disabled mouse-over tracking for the specified QuickTime VR movie.
Use QTVRSetMouseOverTracking (described in the section "QTVRSetMouseOverTracking" ) to change the mouse-over tracking state of a QuickTime VR movie. Use QTVRMouseEnter (described in the section "QTVRMouseEnter" ) and QTVRMouseWithin (described in the section "QTVRMouseWithin" ) to handle the cursor's entering and remaining in a QuickTime VR movie.
You can use the QTVRGetMouseDownTracking function to get the current state of mouse-down tracking.
Boolean QTVRGetMouseDownTracking (QTVRInstanceqtvr);
The QTVRGetMouseDownTracking function returns, as its function result, a Boolean value that indicates whether QuickTime VR is currently handling mouse-down tracking for the QuickTime VR movie specified by the qtvr parameter ( true ) or not ( false ). By default, QuickTime VR tracks mouse clicks in a QuickTime VR movie and triggers hot spots as necessary.
You can use the QTVRSetMouseDownTracking function to set the state of mouse-down tracking.
OSErr QTVRSetMouseDownTracking (QTVRInstance qtvr, Booleanenable);
The QTVRSetMouseDownTracking function sets the mouse-down tracking state of the QuickTime VR movie specified by the qtvr parameter to the state specified by the enable parameter. By default, QuickTime VR tracks mouse clicks in a QuickTime VR movie and triggers hot spots as appropriate. If you disable mouse-down tracking (by passing false in the enable parameter), you must call the QTVRMouseDown , QTVRMouseStillDown , and QTVRMouseUp functions at the appropriate times to handle user actions.
Use QTVRGetMouseDownTracking (described in the section "QTVRGetMouseDownTracking" ) to get the current mouse-down tracking state of a QuickTime VR movie.
You can use the QTVRMouseDown function to handle the user's clicking the mouse button when the cursor is in a QuickTime VR movie for which mouse-down tracking is disabled.
OSErr QTVRMouseDown (QTVRInstanceqtvr,
Pointpt,
UInt32 when,
UInt16 modifiers,
UInt32*hotSpotID,
WindowPtr w);
The QTVRMouseDown function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseDown also performs any other tasks that are typically performed when the user clicks the mouse button when the cursor is in a QuickTime VR movie.
You need to call QTVRMouseDown only if you have disabled mouse-down tracking for the specified QuickTime VR movie.
Use QTVRSetMouseDownTracking (described in the section "QTVRSetMouseDownTracking" ) to change the mouse-down tracking state of a QuickTime VR movie. Use QTVRMouseStillDown (described in the section "QTVRMouseStillDown" ) and QTVRMouseUp (described in the section "QTVRMouseUp" ) to handle the mouse button's being held down and released.
You can use the QTVRMouseStillDown function to handle the user's holding down the mouse button while the cursor is in a QuickTime VR movie for which mouse-down tracking is disabled.
OSErr QTVRMouseStillDown (
QTVRInstanceqtvr,
Pointpt,
UInt32*hotSpotID,
WindowPtr w);
The QTVRMouseStillDown function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseStillDown also performs any other tasks that are typically performed when the user holds down the mouse button when the cursor is in a QuickTime VR movie.
You should call QTVRMouseStillDown repeatedly for as long as the user holds down the mouse button while the cursor is in the specified QuickTime VR movie.
You need to call QTVRMouseStillDown only if you have disabled mouse-down tracking for the specified QuickTime VR movie.
Use QTVRSetMouseDownTracking (described in the section "QTVRSetMouseDownTracking" ) to change the mouse-down tracking state of a QuickTime VR movie. Use QTVRMouseDown (described in the section "QTVRMouseDown" ) and QTVRMouseUp (described in the section "QTVRMouseUp" ) to handle the mouse button's being clicked and released.
You can use the QTVRMouseUp function to handle the user's releasing the mouse button while the cursor is in a QuickTime VR movie for which mouse-down tracking is disabled.
OSErr QTVRMouseUp (QTVRInstance qtvr, Pointpt, UInt32*hotSpotID, WindowPtr w);
The QTVRMouseUp function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseUp also performs any other tasks that are typically performed when the user releases the mouse button after clicking it when the cursor is in a QuickTime VR movie.
You need to call QTVRMouseUp only if you have disabled mouse-down tracking for the specified QuickTime VR movie.
Use QTVRSetMouseDownTracking (described in the section "QTVRSetMouseDownTracking" ) to change the mouse-down tracking state of a QuickTime VR movie. Use QTVRMouseDown (described in the section "QTVRMouseDown" and QTVRMouseStillDown (described in the section "QTVRMouseStillDown" to handle the mouse button's being clicked and held down.
You can use the the QTVRMouseStillDownExtended function the same way you use the QTVRMouseStillDown function, to handle the user's holding down the mouse button while the cursor is in a QuickTime VR movie for which mouse-down tracking is disabled. The QTVRMouseStillDownExtended function uses the same intercept as the QTVRMouseStillDown function but has has two additional parameters.
Internally, QuickTime VR always uses the QTVRMouseStillDownExtended function instead of QTVRMouseStillDown . Developers implementing their own mouse down tracking don't need to use the extended version unless they also intercept the procedure and need the added parameters.
OSErr QTVRMouseStillDownExtended (
QTVRInstanceqtvr,
Pointpt,
UInt32*hotSpotID,
WindowPtr w,
UInt32 when,
UInt16 modifiers);
The QTVRMouseStillDown function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseStillDown also performs any other tasks that are typically performed when the user holds down the mouse button when the cursor is in a QuickTime VR movie.
You should call QTVRMouseStillDown repeatedly for as long as the user holds down the mouse button while the cursor is in the specified QuickTime VR movie.
You need to call QTVRMouseStillDown only if you have disabled mouse-down tracking for the specified QuickTime VR movie.
Use QTVRSetMouseDownTracking (described in the section "QTVRSetMouseDownTracking" ) to change the mouse-down tracking state of a QuickTime VR movie. Use QTVRMouseDown (described in the section "QTVRMouseDown" and QTVRMouseUp (described in the section "QTVRMouseUp" ) to handle the mouse button's being clicked and released.
You can use the QTVRMouseUpExtended function the same way you use the QTVRMouseUp function, to handle the user's releasing the mouse button while the cursor is in a QuickTime VR movie for which mouse-down tracking is disabled. The QTVRMouseUpExtended function uses the same intercept as the QTVRMouseUp function but has has two additional parameters.
Internally, QuickTime VR always uses the QTVRMouseUpExtended function instead of QTVRMouseUp . Developers implementing their own mouse down tracking don't need to use the extended version unless they also intercept the procedure and need the added parameters.
OSErr QTVRMouseUpExtended (
QTVRInstance qtvr,
Pointpt,
UInt32*hotSpotID,
WindowPtr w,
UInt32 when,
UInt16 modifiers);
The QTVRMouseUpExtended function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseUpExtended also performs any other tasks that are typically performed when the user releases the mouse button after clicking it when the cursor is in a QuickTime VR movie.